COMMENT ⊗   VALID 00008 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	USER PROGRAM DOCUMENTATION			       SEPTEMBER 1973
C00004 00003	USING CRE.
C00007 00004	PRIMER
C00011 00005	CRE TELETYPE COMMANDS
C00015 00006	CRE TELETYPE COMMANDS
C00019 00007	SAIL INTERFACING TO CRE.
C00028 00008	LISP INTERFACING TO CRE.
C00032 ENDMK
C⊗;
USER PROGRAM DOCUMENTATION			       SEPTEMBER 1973
draft - draft - draft - draft - draft - draft - draft - draft - draft


                    CRE  -  Contour Region Edge.

                          Bruce g. Baumgart


ABSTRACT:

	This document  explains the  keyboard commands  of CRE, a  2D
image processing  program that converts video television rasters into
a contour map like data structure suitable for input to GEOMED.

CONTENTS:

	1.0	INTRODUCTION.
	2.0	PRIMER.
	3.0	COMMAND LETTERS.
	4.0	EXTENDED COMMANDS.
	5.0	FILE FORMATS.
	6.0	SAIL and LISP interfacing.


	This research was supported in part  by the Advanced Research
Projects  Agency of  the  Office of  the Secretary  of  Defense under
Contract No. SD-183.

	The views  and  conclusions contained  in this  document  are
those  of the  author and  should not  be interpreted  as necessarily
representing  the official policies, either  expressed or implied, of
the  Advanced   Research  Project   Agency  or   the  United   States
Government.
USING CRE.

	A. PRIMER ON RUNNING CRE.
	B. TELETYPE COMMANDS.
	C. SAIL INTERFACING.
	D. LISP INTERFACING.


PRIMER ON RUNNING CRE.


Single Image Contouring.

	The Stanford  copy of  CRE is  run by  typing "R  CRE".   CRE
displays  only  on a  III console,    however it  will  work (without
displays) when run  from a Data Disc  console.  The  command  scanner
is a  simple character jump table;  the command scanner will  type an
asterisk  when it is  listening for teletype  input. Carriage returns
following  commands  are  unnecessary  but  harmless;  most  commands
signal  their  completion by  displaying  something  or  by typing  a
carriage return. Some commands require arguments or file names.   The
question mark, "?", command  will display a summary of  all the other
commands.

	Command  characters may be  modified by the  control and meta
shift keys; such  keying will be  indicated in  this document by  the
prefixing  the characters  "α", "β",   and  "ε" to  indicate control,
meta or both meta-control shift keying respectively.

	The command "T" will take a four  bit television picture from
camera  number one. The command  "H" will display a  histogram of the
television picture.   The command  character SPACE  will refresh  the
image you had before the  histogram display. The command "C" followed
by a  list of octal numbers followed by a carriage return will make a
contour image and display it. Thus the teletype  discourse for taking
and  contouring  a single television image  should have the following
appearance:

↑C

.R CRE

*T
*H 
*C20 40 60
*

	All  the images  in  this  document were  made  with 3  or  7
equally  spaced contours; for which  cases the commands  "Q" and "αQ"
will automatically specify  contour cuts are  20, 40,  60 or 10,  20,
30, 40, 50, 60, 70 respectively.
PRIMER

IMAGE INPUT, OUTPUT AND XGP'ing.

	After you have  an image and  its contours; you can  save one
or the  other or both on  disk files; or print one  or the other. The
"O" command will output a video  image file, in the new hand-eye  200
octal word header format. The "I"  will input a video image from such
a  hand-eye file; if the file  is not 216 by  288, then the center of
the image will be placed  coincident with the center of a 216  by 288
window and  the image will be  repacked with undefined  pixels set to
zero. Both the "I" and the "O"  commands will ask for a filename;  if
an extension  is  not explicitly  given the  default extension  "TMP"
will  be used. The  "αO" command will  output the  CRE data structure
and the  "αI" command  will input  CRE data  structure, naturally  the
default extension is "CRE".

	The "X"  command will output  a video image  to the  XGP. The
"εC"  command followed  by a  list of octal  numbers will  output the
HSEG and VSEG;  raw vector  contours, to  the XGP.   The "P"  command
will  output  the  currently  displayed III  buffer,   the
default  extension is "III".  Finally, the "J"  command  enhances the
contrast of an image for the sake of its appearance on the XGP.

INTERACTIVE (MANUAL) MULTI IMAGE PROCESSING.

	Taking or  inputing new  television images,   and  contouring
them using  the "C" command or the "Q" command  will form a film data
structure.  Images  can be explicitly compared  and linked by  typing
"M" match command  which links the latest image  with the immediately
previous  image. The "Z" command will zero  the data structure of all
images.

AUTOMATIC MULTI IMAGE PROCESSING.

	The "A" command  is for automatic turn table  perception, CRE
takes  64 pictures  from  camera #3  while rotating  the  turn table,
outputs a  file and  exits  (returning control  to the  3D  geometric
editor). The turn  table is manually moved small amounts  by the four
possible  "Y" commands: "Y",  "αY", "βY", and  "εY". Numeric absolute
and relative positioning of  the turntable is under the  "U" command;
the details of which are still being developed.
CRE TELETYPE COMMANDS

VIDEO COMMANDS

  T	 Take a 4-bit television picture.
 αT	 Take a 6-bit television picture.
  S	 Select camera number, default is camera #1.
 αS	 Set TCLIP, default is 0.
 βS	 Set BCLIP, default is 7.
 εS	 Shrink node space. Calls node storage compactor.

	The two  command characters  "T" and  "S" control live  video
camera input.  The default camera is camera #1  on the Cohu camera on
the hand eye table. Camera #0 is the Cart Receiver, camera #2  is the
sierra hand eye camera,  and camera #3 is one or  the other old brown
cameras depending  on which coax is plugged up, the brown camera near
III23 is the Font Camera  and the brown camera near the  turntable is
the GEOMED Camera.

INPUT OUTPUT COMMANDS

  I      Input TMP file.	Television image from disk file.
 αI      Input CRE file.	Contour film from disk file.

  O      Output TMP file.	Television image to disk file.
 αO      Output CRE file.	Contour film to disk file.

  X      Output video image to XGP.
  P      Output III file.	III buffer for calcomp plotter.
 εC   	 Output VIC contour edges to XGP.
	 This command requires a list of octal numbers.
  J   	 Contrast enhancement for the sake of XGP appearance.
  #	 Type twenty CRLF's to clear page printer.
  ?	 Display help summary of CRE commands.

IMAGE CONTOURING COMMANDS

   C   Cut at given threshold levels.
   Q   Cut at equally spaced conttours, three cuts: 20, 40, 60.
  αQ   Seven cuts: 10, 20, 30, 40, 50, 60, 70.

   E	Enable all CRE processing.
   D	Disable all steps except contouring.

   M	 Compare and mate match current image with previous.
   W	 Enter Arc Width Table alter mode.
CRE TELETYPE COMMANDS

NODE FOLLOWING COMMANDS

 +				Fetch film node.
 !				Flush node display.

 , .	CW,,CCW         	Fetch Ring links.
 < >	DAD,,SON        	Fetch Tree links.
	TYPE,,RELLOC
 ∪ ∩	ENDO,,EXO       	Fetch nested polygon tree links.
 ≤ ≥	ALT,,NCNT       	Fetch alternate shape or arc link.
 ⊂ ⊃	NGON,,PGON      	Fetch nested polygon tree links.
 ∨ ∧	NTIME,,PTIME    	Fetch time line links.

	These 14 commands  allow detailed inspection of the  CRE data
structure  by showing the  contents of a  node.  Data  halfwords of a
node are displayed  in octal; link  halfwords are displayed  prefixed
with a  letter indicating the type  of node being pointed  at; a zero
link is displayed as "NIL".

	The  FILM  node,    which  is  the  root  of  the whole  data
structure is  fetched and  displayed by the  "+" command.   From  the
Film, the  ">" command can be  used to get SON(FILM)  which is always
the first image, and  ">" command of  an image will  get a level  and
">"  of  a  level  will get  a  polygon.  Vectors  and  polygons  are
intensified  when  their  contents are  being  displayed.   The  exit
command is "!", which leaves the screen less cluttered.

WINDOW SCROLLING COMMANDS

  ;      Move camera left.
  :      Move camera right.
  (      Move camera down.
  )      Move camera up.

  -      Zoom out, shrink displayed image.
  *      Zoom in,  expand displayed image.
 αZ      Reset scrolling window to it initial position and size.
  /      Halve strength of scrolling delta.
  \      Double strength of scrolling delta.

  ↔	 Single step displayed image forwards.
 α↔	 Single step displayed image backwards.
 β↔	 Run film display forwards.
 ε↔	 Run film display backwards.

	The first  several commands allow  minute examination  of the
image by  magnification and window positioning. The command character
"↔" allows  single stepping  thru  the film  of images  or  continous
display of the film forwards or backwards.
SAIL INTERFACING TO CRE.

	It should be possible to embed the CRE machine code  under  a
SAIL  core  image;  however  I do not intend to do this work. For the
present, the CRE interface to SAIL is only realized via a  disk  file
transfer  of  the  data  structure.   A  CRE file may be read into an
integer array in binary mode as illustrated below.

	The  first  word  of a CRE file is the first word of the film
node which contains the size of the file in words. The film node  has
address  0;  the  next node has address 7; and so on in multiples of
seven.  There are no empty nodes in a CRE file.  The  following  SAIL
program will read in a CRE file named X:

	COMMENT EXAMPLE OF SAIL INPUT OF A CRE FILE;
	BEGIN	"TEST"
		INTEGER SIZE;
		OPEN(1,"DSK",8,3,0,0,0,0);
		LOOKUP(1,"X.CRE",0);
		SIZE ← WORDIN(1);
	BEGIN
		INTEGER ARRAY NODE[0:SIZE];
		ARRYIN(1,NODE[1],SIZE-1);
		RELEASE(1);
		"MAIN PROGRAM.";
	END;
	END;

After the NODE array is loaded, CRE links and data may be accessed by
their  document names in a reasonable node-link notation using macros
like the following:

	DEFINE CW(Q)  = "(NODE[Q] LSH -18)";
	DEFINE CCW(Q) = "(NODE[Q] LAND '777777)";
	DEFINE DAD(Q) = "(NODE[Q+1] LSH -18)";
	DEFINE SON(Q) = "(NODE[Q+1] LAND '777777)";

So  that  the first vertex of the first polygon of the first level of
the first image of the film can be obtained:

	INTEGER FILM,IMAGE,LEVEL,POLYGON,VERTEX;

	FILM ← 0;
	LEVEL ← SON(FILM);
	POLYGON ← SON(LEVEL);
	VERTEX ← SON(POLYGON);

The  user may note that SAIL will compile three or more instructions
for what is known as a PDP-10 halfword operation; also  if  the  user
converts  the  CRE  nodes  and links into LEAP items and associations
then an  overhead  of  from  ten  to  one  hundred  instructions  per
"halfword operation" will be incurred.
LISP INTERFACING TO CRE.

	It should be possible  to embed the CRE machine  code under a
LISP  core image; however I  do not intend  to do this  work. For the
present, the CRE interface to LISP  is only realized via a disk  file
transfer of  the data structure.   A CRE file  may be read  into LISP
binary  program space  and accessed  using the CRE  nomensclature (11
link  names  and  13  datum  names)  by  means  of  the  S-Expression
subroutines provided  in the file CRE.LSP[CRE,BGB].   The subroutines
work in both the old Stanford LISP 1.6 as well as the newer UCI  LISP
and Micro Planner, PLNR. The CRE.LSP[CRE,BGB] can be loaded either by
one or the other of the following two LISP statements:

	(DSKIN(CRE,BGB)(CRE.LSP))
	(INC(INPUT(CRE,BGB)(CRE.LSP)))

A CRE film file is read into LISP binary program space by one of the
three possible INCRE formats:

	(INCRE filename)
	(INCRE filename project)
	(INCRE filename project programmer)

Filenames should be  six characters or less, projects  and programmer
initials should  be three characters or  less, the filename extension
CRE is  assummed and the  usual PPPN  defaults  occur. If  the  input
succeeds INCRE returns a value T;  if the input fails INCRE returns a
value NIL and prints one or the other of these two messages:

	CRE FILE NOT FOUND.
	CRE FILE REQUIRES 00000 MORE WORDS OF BINARY PROGRAM SPACE.

After a sucessful  INCRE; the film,  image,  level, polygon,  arc and
vector  nodes are  referred to  by integers using  the 11  Link Fetch
Subroutines:

	(CW node)(CCW node)(DAD node)(SON node)(ENDO node)(EXO node)
	(ALT node)(NGON node)(PGON node)(NTIME node)(PTIME node)

The film  node's  address is  the  integer 0,   zero.    So that  the
expression  (SETQ V3(CCW(CCW(SON(SON(SON(SON  0)))))))  will retrieve
the lower right hand corner of the border polygon of the -1  level of
the first image  of the film. The 13 CRE.LSP  datum fetch subroutines
are:

	(ROW node)(COL node)(CRETYPE node)(RELOC node)
	(CNTRST node)(NCNT node)(ZDEPTH node)(PERM node)(AREA node)
	(MXX node)(MYY node)(MZZ node)(PXY node)